Reproducible Data Reports with Quarto

Myles Mitchell @ Jumping Rivers

Welcome!

Connecting to our cloud environment

Cloud Environment

https://quarto-workshop.jumpingrivers.training/welcome/

Password: grapefruit-kiwi

Screenshot of log in page

Before we start…

Who am I?

  • Background in Astrophysics.

  • Data Scientist @ Jumping Rivers:

    • Python support for various clients.

    • Teach courses in Python, SQL, ML.

  • Hobbies include hiking and travelling.

Jumping Rivers

↗ jumpingrivers.com   𝕏 @jumping_uk

  • Machine learning
  • Dashboard development
  • R packages and APIs
  • Data pipelines
  • Code review
     

Introduction to Quarto

What is Quarto?

Quarto is a tool created by Posit (formerly RStudio).

Workflow diagram starting with a qmd file, then Jupyter, then md, then pandoc, then PDF, MS Word, or HTML.
  • “Next-gen” R Markdown: documents that combine code with text.
  • Tables and plots can be quickly regenerated if the data changes.
  • Works for multiple languages and formats (Quarto gallery).
  • These HTML slides were built in Quarto!
  • Quarto files have .qmd extension.
  • Download it from quarto.org/docs/get-started.

Compatible with multiple IDEs

  • RStudio IDE1
  • VS Code2
  • Jupyter
  • Text Editor

What about R Markdown?

  • Quarto has better multi-language support.

       

  • More user-friendly.

  • Better control of the output layouts.

  • There is an R package library(quarto).

  • New features will be added to Quarto.

Creating a new Quarto document

  • File > New File > Quarto Document

  • Set title and author

  • Click Create

  • Save and click Render

YAML header

YAML: Yet Another Markup Language

---
title: "A very cool title"
author: "Myles Mitchell"
format: html
---
  • Set title, subtitle, date, author, etc.
  • Set the output format (pdf, html, revealjs, …).
  • Any formatting that should be applied to the entire document.
  • Import pre-defined styles using Quarto extensions.

Let’s build an HTML report!

  • Text
  • Links
  • Images
  • Code
  • Embedded tables and plots
  • References

Inserting text - Markdown

  • Fonts

    **bold**
*italic*

  • Headings

    # Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6

  • Bullet points (use -, + or *)

    - Banana
- Pear
- Apple

  • Numbered lists (automatic indexing!)

    1. Royal Gala
1. Pink Lady
1. Granny Smith

Including images

  • Use the Visual editor - click Insert –> Figure/Image

  • Or type into a Quarto document:

    ![](img/lemur.jpg){fig-alt="Brown-collared lemur"}
Brown-collared lemur looking directly at the camera

Task 1: Your first Quarto document

  • File > New File > Quarto Document.

  • Set title and author.

  • Click Create.

  • Save and click Render.

  • Add the text from task1.txt.

  • Add a link to the Duke Lemur Center https://lemur.duke.edu/.

  • Add the image of the Mongoose Lemur.

15:00

Code Chunks

… and lemurs…

Loading data

You can load in your data using R:

```{r}
#| message: false
library(readr)
lemurs <- read_csv(
  "https://raw.githubusercontent.com/rfordatascience/tidytuesday/master/data/2021/2021-08-24/lemur_data.csv",
  col_types = cols_only(sex = "c", age_at_wt_mo = "d", weight_g = "d"))
```

Chunk Options

  • Hide the code:

    #| echo: false

  • Show the code and the YAML:

    #| echo: fenced

  • Don’t evaluate the code:

    #| eval: false

  • Hide code messages:

    #| message: false

  • Can set default code behaviour in the YAML header:

    ---
title: "My Document"
author: "Myles Mitchell"
format: html
execute:
  message: false
---

Code collapsing

If we’re just loading in packages, perhaps we should collapse the code…

Code
```{r}
#| message: false
#| code-fold: true
library(dplyr)
library(tidyr)
library(ggplot2)
```

… do some data wrangling, and print the output as a table…

```{r}
#| output-location: slide
df = lemurs |>
  drop_na() |>
  filter(age_at_wt_mo > 12)

df |>
  head() |>
  knitr::kable()
```
sex weight_g age_at_wt_mo
M 1086 125.82
M 1190 129.93
F 947 131.11
F 1174 135.42
M 899 100.64
M 917 101.06

…or include some exploratory plots!

```{r}
#| message: false
#| output-location: slide
#| fig-cap: "Age vs weight of lemurs"
#| fig-alt: "Scatter plot showing positive relationship between lemur age and weight split by sex"
#| out-width: 150%
ggplot(data = df,
       mapping = aes(x = age_at_wt_mo,
                     y = weight_g,
                     colour = sex)) +
  geom_point(alpha = 0.1) +
  geom_smooth(method = "lm") +
  labs(title = "Weight of lemurs",
       x = "Age (months)",
       y = "Weight (g)")
```

Scatter plot showing positive relationship between lemur age and weight split by sex

Age vs weight of lemurs

Inline code

```{r}
num_obs = nrow(lemurs)
```

We can also include code inline, rather than as a separate chunk.

The number of observations is `r num_obs`.

The number of observations is 82609.

Task 2: Adding code

  • Add a code block to load the data and libraries (see task-2.R).

  • Set the code chunk options to hide the code and messages.

  • Add a second code block to make a scatter plot.

  • Add a caption to the plot with the fig-cap code chunk option.

  • Add a final code chunk to find the average weight.

15:00

Not Convinced?

Let’s explore some more use cases!

Polished presentations

  • Great way to demonstrate code:

    ggplot(data = df,
       mapping = aes(x = age_at_wt_mo,
                     y = weight_g,
                     colour = sex)) +
  geom_point(alpha = 0.1) +
  geom_smooth(method = "lm") +
  labs(title = "Weight of lemurs",
       x = "Age (months)",
       y = "Weight (g)")

  • Engaging format for teaching!

  • Flexible CSS styling that can be shared.

Journals

  • LaTeX backend for PDF documents.

  • Try quarto-journals for correctly formatted journal articles!

  • E.g. for the Journal of Statistical Software article:

    ----
title: "My Document"
format:
  pdf: default
  jss-pdf:
    keep-tex: true
---

  • More journal templates at awesome-quarto.

Parameterised reports

  • Add parameters to your document using the YAML header:

    ---
title: "My Report About Penguins"
format: html
params:
  species: "Adelie"
---

  • Access these parameters with params$species

    penguins_subset = dplyr::filter(
  penguins,
  species == params$species
)

Parameterised reports

  • Access these parameters with params$species

    penguins_subset = dplyr::filter(
  penguins,
  species == params$species
)

  • Update from the command line without the need for manual changes!

    quarto render slides.qmd -P species:"Gentoo"

Multi-language support

  • Everything we’ve shown here can also be done in Python!

  • Fence code cells with {python} instead of {r}.

  • VS Code and Jupyter Lab are both supported by Quarto.

  • Inline code and parameters have different syntax in Python.

  • See Python Quarto docs for details.

Publishing

It’s easy to share your documents!

  • Quarto Pub is free to use.

  • GitHub pages available to free GitHub accounts.

  • Top tip: creating an HTML with no external dependencies

    ---
title: "Report with embedded images"
format:
  html:
    embed-resources: true
---

Thanks for listening!